home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 1999 August / SGI Freeware 1999 August.iso / dist / fw_geomview.idb / usr / freeware / info / geomview-2.z / geomview-2
Encoding:
Text File  |  1999-01-26  |  51.8 KB  |  1,421 lines

  1. Info file: geomview,    -*-Text-*-
  2. produced by texinfo-format-buffer
  3. from file: geomview.tex
  4.  
  5.  
  6. 
  7. File: geomview  Node: Lighting Panel, Prev: Materials Panel, Up: Appearance, Next: Cameras
  8.  
  9. The Lighting Panel
  10. ------------------
  11.  
  12. The *Lighting* panel controls the number, position, and color of
  13. the light sources used in shading.
  14.  
  15. The *Lighting* panel is different from the *Appearance* and
  16. *Material* panels in that it always works with the base
  17. appearance.  This is because it usually makes sense to use the same set
  18. of lights for drawing all objects in your scene.
  19.  
  20.  
  21. *LIGHTS*
  22.      The *LIGHTS* browser shows the currently selected light.  Changes
  23.      made using the other widgets on this panel apply to this light.  There
  24.      is always at least one light, the ambient light.
  25.  
  26. *Intensity*
  27.      This slider controls the intensity of the current light.
  28.  
  29. *Color*
  30.      This button brings up a color chooser which lets you select the color
  31.      of the current light.
  32.  
  33. *Add*
  34.      This button adds a light.
  35.  
  36. *Delete*
  37.      This button deletes the current light.
  38.  
  39. *Show Lights*
  40.      This button lets you see and change the positions of the light sources
  41.      in a camera window.  Each light is drawn as long cylinder which is
  42.      supposed to remind you of a light beam.  When you click on the
  43.      *Show Lights* button Geomview goes into "light edit" mode, during
  44.      which you can rotate current light by holding down the left mouse button
  45.      and moving the mouse.  Lights placed in this way are infinitely distant,
  46.      so what you are changing is the angular position.  Click on the
  47.      *Show Lights* button again to return to the previous motion mode
  48.      and to quit drawing the light beams.
  49.  
  50. *Done*
  51.      This button dismisses the *Lighting* panel.
  52.  
  53.  
  54. Geomview's *Appearance*, *Materials*, and *Lighting*
  55. panels are constructed to allow you to easily do most of the appearance
  56. related things that you might want to do.  The appearance hierarchy that
  57. Geomview supports internally, however, is very complex and there are
  58. certain operations that you cannot do with the panels.  The Geomview
  59. command language (gcl) provides complete support for appearance operations.
  60. In particular, the `merge-baseap' command can be used to change the
  61. base appearance (which, except for lighting, cannot be changed by
  62. Geomview's panels).  The `merge-ap' command can be used to change
  63. an individual geom's appearance.  Appearances can also be specified in
  64. OOGL files; for details, *Note Appearances::.
  65.  
  66.  
  67. 
  68. File: geomview  Node: Cameras, Prev: Lighting Panel, Up: Interaction, Next: Saving
  69.  
  70. Cameras
  71. =======
  72.  
  73. A camera in Geomview is the object that corresponds to a camera window.
  74. By default there is only one camera, but it is possible to have as many
  75. as you want.  You can control certain aspects of the way the world is
  76. drawn in each camera window via the *Cameras* panel.
  77. If the target object is a camera, the *Cameras* panel affects that
  78. camera.  If the target object is not a camera, the *Cameras* panel
  79. affects the "current camera".  The current camera is the camera of
  80. the window that the mouse cursor is in, or was in most recently if the
  81. cursor is not in a camera window.  Thus, if you use the keyboard
  82. shortcuts for the actions in the *Cameras* panel while the cursor
  83. is in a camera window, the actions apply to that camera, unless you have
  84. explicitly selected another camera.
  85.  
  86. To create new camera windows, use the `v+' keyboard shortcut,
  87. or see the *File* menu on the *Main* panel.
  88.  
  89.  
  90. *Single-Buffering*
  91.      Normally, geomview windows are *double-buffered*: geomview draws the
  92.      next picture into a hidden window, then switches buffers to make
  93.      it visible all at once.  On many systems, the memory for the hidden buffer
  94.      comes from stealing half the bits in each screen pixel, reducing the color
  95.      resolution.  When single-buffering is enabled, the window flickers as each
  96.      scene is being drawn, but you may get smoother images with reduced grainy
  97.      dithering artifacts.  Single-buffering is possible if Geomview is compiled with
  98.      GL or OpenGL, but not with plain-X graphics.
  99.  
  100. *Dither*
  101.      Many displays offer less than the 24 bits per pixel (8 bits each of red, green,
  102.      and blue) conventionally needed to show smooth gradations of color.  
  103.      When trying to show a color not accurately available on the display,
  104.      Geomview normally *dithers*, choosing pixel colors sometimes brighter,
  105.      sometimes darker than the desired value, so that the average color over an area
  106.      is a better approximation to the true color than a single pixel could be.
  107.      Effectively this loses spatial resolution to gain color resolution.
  108.      This isn't always desirable, though.  Turning *Dither* off
  109.      gives less grainy, but less accurately colored, images.
  110.  
  111. *Software Shading*
  112.      This button controls whether Geomview does shading calculations in software.
  113.      The default is to let the hardware handle them, and in Euclidean space
  114.      this is almost certainly best because it is faster.  In hyperbolic and
  115.      spherical space, however, the shading calculations that the hardware
  116.      does are incorrect.  Click this button to turn on correct but slower
  117.      software shading.
  118.  
  119. *Background Color*
  120.      This button brings up a color chooser which you can use to set the
  121.      background color of the camera's window.
  122.  
  123. *PROJECTION*
  124.      This browser lets you pick between perspective and orthogonal projection
  125.      for this camera.
  126.  
  127. *Near clip*
  128.      This determines the distance in world coordinates of the near clipping
  129.      plane from the eye point.  It must be a positive number.
  130.  
  131. *Far clip*
  132.      This determines the distance in world coordinates of the far clipping
  133.      plane from the eye point.  It must be a positive number and in general
  134.      should be larger than the *Near clip* value.
  135.  
  136. *FOV*
  137.      This is the camera's field of view, measured in its shorter direction.
  138.      In perspective mode, it is an angle in degrees.  In orthographic mode,
  139.      it is the linear size of the field of view.  This number can be modified
  140.      with the mouse in *Cam Zoom* mode.
  141.  
  142. *Focal Length*
  143.      The focal length is intended to suggest the distance from the camera to
  144.      an imaginary plane of interest.  Its value is used when switching
  145.      between orthographic and perspective views (and during stereo viewing),
  146.      so as to preserve apparent size of objects lying at the focal distance
  147.      from the camera.  Focal length also affects interpretation of mouse-based
  148.      translational motions.  Speed of forward motion (in translate, fly and
  149.      orbit modes) is proportional to focal length; and objects lying at the
  150.      focal distance from the camera translate laterally at the same rate as
  151.      the mouse cursor.  Finally, in N-D projection mode, cameras are displaced
  152.      back by the focal distance from the 3-D projection of the world origin.
  153.  
  154. *Lines Closer*
  155.      This number has to do with the way lines are drawn.  Normally Geomview's
  156.      z-buffering algorithm can get confused when drawing lines that lie
  157.      exactly on surfaces (such as the edges of an object); due to machine
  158.      round-off error, sometimes the lines appear to be in front of the
  159.      surface and sometimes they appear behind it.  The *Lines Closer*
  160.      value is a fudge factor --- Geomview nudges all the lines that it draws
  161.      closer to the camera by this amount.  The number should be a small
  162.      integer; try 5 or 10.  0 turns this feature off completely.  Choosing
  163.      too large a value will make lines visible even though they should be
  164.      hidden.
  165.  
  166. *SPACE MODEL*
  167.      This determines the model used to draw the world.  It is most useful in
  168.      hyperbolic and spherical spaces.  You probably don't need to touch this
  169.      browser if you stay in Euclidean space.  For more information about
  170.      these models, *Note Non-Euclidean Geometry::.
  171.      *Virtual*
  172.           This is the default model and represents the natural view from inside
  173.           the space.
  174.  
  175.      *Projective*
  176.           The projective model of hyperbolic and spherical space.  Geoms move
  177.           under isometries of the space, and cameras move by Euclidean motions.
  178.           By default in the projective model, the Euclidean unit sphere is drawn.
  179.           In hyperbolic space this is the sphere at infinity.  In Euclidean space
  180.           the projective model is the same as the virtual model except that the
  181.           sphere is drawn by default.
  182.  
  183.      *Conformal*
  184.           The conformal model of hyperbolic and spherical space.  Geoms move under
  185.           isometries of the space, and cameras move by Euclidean motions.  In
  186.           Euclidean space, the conformal model amounts to inverting everything in
  187.           the unit sphere.
  188.  
  189. *Draw Sphere*
  190.      This controls whether Geomview draws the unit sphere.  By default the
  191.      unit sphere appears in the projective and conformal models.  In
  192.      hyperbolic space this is the sphere at infinity.  In spherical space it
  193.      is the equatorial sphere.
  194.  
  195. *Done*
  196.      This button dismisses the *Cameras* panel.
  197.  
  198.  
  199. 
  200. File: geomview  Node: Saving, Prev: Cameras, Up: Interaction, Next: Commands
  201.  
  202. Saving your work
  203. ================
  204.  
  205. Geomview's *Save* panel lets you store Geomview objects and other
  206. information in files that you can read back into Geomview or other
  207. programs.
  208. To use the *Save* panel you select the desired format in the
  209. browser next to the word *Save*, enter the name of the object you
  210. want to save in the text field next to the word *for*, and enter
  211. the name of the file you wish to save to in the long text field next to
  212. the word *in*.  You can then either hit `RET' or click
  213. on the *OK* button.  When the file has been written, the *Save*
  214. panel disappears.  If you want to dismiss the *Save* panel without
  215. writing a file, click the *Cancel* button.
  216.  
  217. If you specify `-' as the file name, Geomview will write the file
  218. to standard output, i.e. in the shell window from which you invoked
  219. Geomview.
  220.  
  221. The possible formats are given below.  The kind of object that can
  222. be written with each format is given in parentheses.
  223.  
  224.  
  225. *Commands (any object)*
  226.      This write a file of gcl commands containing all information about
  227.      the object.  Loading this file later will restore the object as well as
  228.      all other information about it, such as appearance, transformations,
  229.      etc.
  230.  
  231. *Geometry alone (geom)*
  232.      This writes an OOGL file containing just the geometry of the object.
  233.  
  234. *Geometry [in world] (geom)*
  235.      This writes an OOGL file containing just the geometry of the object,
  236.      transformed under Geomview's current transformation for this object.
  237.      Use this if you have moved the object from its initial position and want
  238.      to save the new position relative to the world.
  239.  
  240. *Geometry [in universe] (geom)*
  241.      This writes an OOGL file containing just the geometry of the geom,
  242.      transformed under both the object's transformaton and the world's
  243.      transformation.
  244.  
  245. *RMan [->tiff] (camera)*
  246.      Writes a RenderMan file which when rendered creates a tiff image.
  247.  
  248. *RMan [->frame] (camera)*
  249.      Writes a RenderMan file which when rendered causes an image to appear in
  250.      a window on the screen.
  251.  
  252. *SGI snapshot (camera)*
  253.      Write an SGI raster file.  A bell rings when the snapshot is complete.
  254.      Only available on SGI systems.
  255.  
  256. *PPM Screen snapshot (camera)*
  257.      Take a snapshot of the given window and save it as a PPM image.
  258.      If you specify a string beginning with a vertical bar (`|')
  259.      as the file name, it's interpreted as a Bourne shell command
  260.      to which the PPM data should be piped, as in
  261.      `| pnmtotiff > snap.tiff' or `| convert -geometry 50% ppm:- snap.gif'.
  262.  
  263.      PPM screen snapshots are only available with GL and Open GL,
  264.      not plain X graphics.  The window should be entirely on the screen.
  265.      Geomview will ensure that no other windows cover it while the snapshot
  266.      is taken.
  267.  
  268. *PPM software snapshot (camera)*
  269.      Writes a snapshot of that window's current view, as a PPM image, to the
  270.      given file.  The file name may be a Bourne shell command preceded by a vertical
  271.      bar (`|'), as with the PPM screen snapshot.  The software snapshot, though,
  272.      is produced by using a built-in software renderer (related to the X-windows
  273.      renderer).  It doesn't matter whether the window is visible or not,
  274.      and doesn't depend on GL or OpenGL.  It also doesn't support some features,
  275.      such as texture mapping.
  276.  
  277. *Postscript snapshot (camera)*
  278.      Writes a Postscript snapshot of the camera's view.  It's made by
  279.      breaking up the scene into lines and polygons, sorting by depth, and
  280.      generating Postscript lines and polygons for each one.  Advantages over
  281.      pixel-based snapshot images: resolution is very high, so edges
  282.      look sharp even on high-resolution printers, or comparable-resolution images
  283.      are typically much more compact.  Disadvantages: depth-sorting
  284.      gives good results on some scenes, but can be wildly wrong as a hidden-surface
  285.      removal algorithm for other scenes.  Also, Postscript doesn't offer
  286.      smoothly interpolated shading, only flat shading for each facet.
  287.  
  288. *Camera (camera)*
  289.      Writes an OOGL file of a camera.
  290.  
  291. *Transform [to world] (any object)*
  292.      Writes an OOGL transform file giving Geomview's transform for the object.
  293.  
  294. *Transform [to universe] (any object)*
  295.      Writes an OOGL transform file giving a transform which is the
  296.      composition of Geomview's transform for the object and the transform for
  297.      the world.
  298.  
  299. *Window (camera)*
  300.      Writes an OOGL window file for a camera.
  301.  
  302. *Panels*
  303.      Writes a gcl file containing commands which record
  304.      the state of all the Geomview panels.  Loading this file later will
  305.      restore the positions of all the panels.
  306.  
  307.  
  308. 
  309. File: geomview  Node: Commands, Prev: Saving, Up: Interaction, Next: Keyboard Shortcuts
  310.  
  311. The Commands Panel
  312. ==================
  313.  
  314. The *Commands* panel lets you type in a gcl command.  When
  315. you hit `RET', Geomview interprets the command and prints any
  316. resulting output or error messages on standard output.  You can edit the
  317. text and hit `RET' as many times as you like, in general,
  318. whenever you hit `RET' with the cursor in the *Commands*
  319. panel, Geomview tries to interpret whatever text you have typed in the
  320. text field as a command.
  321.  
  322. The *Obscure* panel is for relatively obscure things that don't
  323. really belong on any of the other panels.  In the present version of
  324. Geomview, the *Obscure* panel includes the *NORMALIZE GEOMETRY*
  325. browser, which controls the kind of geometry normalization that Geomview does,
  326. and several buttons affecting motion style.
  327. [Move this.]
  328. Normalization is a kind of scaling; Geomview can scale an object so that
  329. it fits within a certain region.  The main point of normalization is to
  330. allow you to easily view all of an object without having to worry about
  331. how big it is.  We are gradually replacing Geomview's normalization
  332. feature with more robust camera positioning features.  In general, the
  333. best way to make sure you are seeing all of an object is to use the
  334. *Look At* button on the *Tools* panel.  Normalization may
  335. be completely replaced by this and other features in a future version of
  336. Geomview.
  337.  
  338. Normalization is a property that applies to each geom separately.  The
  339. *NORMALIZE GEOMETRY* browser affects the normalization property
  340. of target geom.  If the target geom is "World", it affects all geoms.
  341.  
  342.  
  343. *None*
  344.      Do no normalization.
  345.  
  346. *Individual*
  347.      Normalize this geom to fit within a unit sphere.
  348.  
  349. *Sequence*
  350.      This resembles "Individual", except when an object is changing.  Then,
  351.      "Individual" tightly fits the bounding box around the object whenever it
  352.      changes and normalizes accordingly, while "Sequence" normalizes the
  353.      union of all variants of the object and normalizes accordingly.
  354.  
  355. *Keep*
  356.      This leaves the current normalization transform unchanged when the
  357.      object changes.  It may be useful to apply "Individual" or "Sequence"
  358.      normalization to the first version of a changing object to bring
  359.      it in view, then switch to "Keep".
  360.  
  361.  
  362. 
  363. File: geomview  Node: Keyboard Shortcuts, Prev: Commands, Up: Interaction, Next: OOGL File Formats
  364.  
  365. Keyboard Shortcuts
  366. ==================
  367.  
  368. Most actions that you can do through Geomview's panels have equivalent
  369. keyboard shortcuts so that you can do the same action by typing a
  370. sequence of keys on the keyboard.  This is useful for advanced users who
  371. are familiar with Geomview's capabilities and want to work quickly
  372. without having to have lots of panels cluttering up the screen.
  373. Keyboard shortcuts usually are indicated in square brackets ([ ]) near
  374. the corresponding item in a panel.  For example, the keyboard shortcut
  375. for *Rotate* mode is 'r'; this is indicated by "[r]" appearing
  376. before the word "Rotate" in the *MOTION MODE* browser.  To
  377. use this keyboard shortcut just hit the `r' key while the mouse
  378. cursor is in any Geomview window.  You don't need to press the `RET'
  379. or `SPACE' keys.
  380.  
  381. Some keyboard shortcuts consist of more than one key.  In these cases
  382. just type the keys one after the other, with no `RET'
  383. afterwards.  Keyboard shortcuts are case sensitive.  You can cancel a
  384. multi-key keyboard shortcut that you have started by typing any invalid
  385. key, for example the space bar.
  386.  
  387. Keyboard commands apply while the cursor is in any camera window and
  388. most control panels.
  389.  
  390. Many keyboard shortcuts allow numeric arguments which you type as a
  391. prefix to the command key(s).  For example, the shortcut for
  392. *Near clip* in the camera panel is `v n'.  To set the near
  393. clip plane to `0.5', type `0.5vn'.  Commands that don't take a
  394. numeric prefix toggle or reset the current value.
  395.  
  396. Most commands allow one of the following selection prefixes.  If none is
  397. provided the command applies to the target object.
  398.  
  399. `g'
  400.      world geom    
  401. `g#'
  402.      #'th geom
  403. `g*'
  404.      All geoms
  405. `c'
  406.      current camera
  407. `c#'
  408.      #'th camera
  409. `c*'
  410.      All cameras
  411.  
  412. For example, `g4af' means toggle the face drawing of object
  413. *g4*.
  414.  
  415. Simply typing a selection prefix, like `g4', doesn't yet select an object;
  416. that only happens when a command, like `ae', follows the prefix.
  417. To select an object as the target without doing anything else to it,
  418. use the `p' command.  So `g3p' selects object g3.
  419.  
  420. The text field in the upper left corner of the *Main* panel
  421. shows the state of the current keyboard shortcut.
  422.  
  423. In addition to the keyboard shortcuts for the panel commands, there is
  424. also a shortcut for picking a target object: type the short name of the
  425. object followed by `p'.  For example, to select object *g3*,
  426. type `g 3 p'.  This only works with the short names --- the ones
  427. that appear in square brackets ([ ]) in the *Targets* browser of
  428. the *Main* panel.
  429.  
  430. Below is a summary of all keyboard shortcuts.
  431.  
  432. Draw
  433.              `af'
  434.      
  435.               Faces
  436.               `ae'
  437.      
  438.               Edges
  439.               `an'
  440.      
  441.               Normals
  442.               `ab'
  443.      
  444.               Bounding Boxes
  445.               `aV'
  446.      
  447.               Vectors
  448.          Shading
  449.      
  450.              `0as'
  451.      
  452.               Constant
  453.               `1as'
  454.      
  455.               Flat
  456.               `2as'
  457.      
  458.               Smooth
  459.               `3as'
  460.      
  461.               Smooth, non-lighted
  462.               `aT'
  463.      
  464.               allow transparency
  465.               `at'
  466.      
  467.               texture mapping
  468.          Other
  469.      
  470.              `av'
  471.      
  472.               eVert normals: always face viewer
  473.               `#aw'
  474.      
  475.               Line Width (pixels)
  476.               `aC'
  477.      
  478.               handle concave polygons
  479.               `#vc'
  480.      
  481.               edges Closer than faces (try 5-100)
  482.          Color
  483.      
  484.              `Cf'
  485.      
  486.               faces
  487.               `Ce'
  488.      
  489.               edges
  490.               `Cn'
  491.      
  492.               normals
  493.               `Cb'
  494.      
  495.               bounding boxes
  496.               `CB'
  497.      
  498.               background
  499.          Motions
  500.      
  501.              `r'
  502.      
  503.               rotate
  504.               `t'
  505.      
  506.               translate
  507.               `z'
  508.      
  509.               zoom FOV
  510.               `f'
  511.      
  512.               fly
  513.               `o'
  514.      
  515.               orbit
  516.               `s'
  517.      
  518.               scale
  519.               `w'
  520.      
  521.               recenter target
  522.               `W'
  523.      
  524.               recenter all
  525.               `h'
  526.      
  527.               halt
  528.               `H'
  529.      
  530.               halt all
  531.               `@'
  532.      
  533.               select center of motion (e.g. `g 3 @')
  534.               `L'
  535.      
  536.               Look At object
  537.          Viewing
  538.      
  539.              `0vp'
  540.      
  541.               Orthographic view
  542.               `1vp'
  543.      
  544.               Perspective view
  545.               `vd'
  546.      
  547.               Draw other views' cameras
  548.               `#vv'
  549.      
  550.               field of View
  551.               `#vn'
  552.      
  553.               near clip distance
  554.               `#vf'
  555.      
  556.               far clip distance
  557.               `v+'
  558.      
  559.               add new camera
  560.               `vx'
  561.      
  562.               cursor on/off
  563.               `vb'
  564.      
  565.               backfacing poly cull on/off
  566.               `#vl'
  567.      
  568.               focal length
  569.               `v~'
  570.      
  571.               Software shading on/off
  572.          Panels
  573.      
  574.              `Pm'
  575.      
  576.               Main
  577.               `Pa'
  578.      
  579.               Appearance
  580.               `Pl'
  581.      
  582.               Lighting
  583.               `Po'
  584.      
  585.               Obscure
  586.               `Pt'
  587.      
  588.               Tools
  589.               `Pc'
  590.      
  591.               Cameras
  592.               `PC'
  593.      
  594.               Commands
  595.               `Pf'
  596.      
  597.               Files
  598.               `Ps'
  599.      
  600.               Save
  601.               `P-'
  602.      
  603.               read commands from tty
  604.               `PA'
  605.      
  606.               Credits ("about")
  607.          Lights
  608.      
  609.              `ls'
  610.      
  611.               show lights
  612.               `le'
  613.      
  614.               edit lights
  615.          Space
  616.      
  617.              `me'
  618.      
  619.               Euclidean
  620.               `mh'
  621.      
  622.               Hyperbolic
  623.               `ms'
  624.      
  625.               Spherical
  626.          Model
  627.      
  628.              `mv'
  629.      
  630.               Virtual
  631.               `mp'
  632.      
  633.               Projective
  634.               `mc'
  635.      
  636.               Conformal
  637.          Other
  638.      
  639.              `0N'
  640.      
  641.               normalizaton: none
  642.               `1N'
  643.      
  644.               normalization: each
  645.               `2N all'
  646.      
  647.               normalization: all
  648.               `ui'
  649.      
  650.               motion: Inertia
  651.               `uc'
  652.      
  653.               motion: Constrain to axis
  654.               `uo'
  655.      
  656.               motion: object's Own coordinates
  657.               `<'
  658.      
  659.               `Pf'
  660.      
  661.               load geometry/command file
  662.               `dd'
  663.      
  664.               delete target object
  665.               `>'
  666.      
  667.               `Ps'
  668.      
  669.               save state to file
  670.               `TV'
  671.      
  672.               NTSC mode toggle
  673.               `p'
  674.      
  675.               pick as target object (e.g. `g 3 p')
  676.               With no prefix, selects the object under the
  677.               mouse cursor (like double-clicking the right mouse)
  678.     
  679. 
  680. File: geomview  Node: OOGL File Formats, Prev: Keyboard Shortcuts, Up: Top, Next: Conventions
  681.  
  682. OOGL File Formats
  683. *****************
  684.  
  685. The objects that you can load into Geomview are called OOGL objects.
  686. OOGL stands for "Object Oriented Graphics Library"; it is the library
  687. upon which Geomview is built.
  688.  
  689. There are many different kinds of OOGL objects.  This chapter gives
  690. syntactic descriptions of file formats for OOGL objects.
  691.  
  692. Examples of most file types live in Geomview's `data/geom'
  693. directory.
  694.  
  695. * Menu:
  696.  
  697. * Conventions::                   Conventions.
  698. * Object File Formats::           Object File Formats.
  699. * Non-geometric objects::         Non-geometric objects.
  700.  
  701. 
  702. File: geomview  Node: Conventions, Prev: OOGL File Formats, Up: OOGL File Formats, Next: Common syntax
  703.  
  704. Conventions
  705. ===========
  706.  
  707. * Menu:
  708.  
  709. * Common syntax::                  Syntax Common to All OOGL File Formats.
  710. * File names::                     File Names.
  711. * Vertices::                       Vertices.
  712. * Surface normal directions::      Surface normal directions.
  713. * Transformation matrices::        Transformation matrices.
  714. * Binary format::                  Binary format.
  715. * References::                     Embedded objects and external-object references.
  716. * Appearances::                    Appearances.
  717.  
  718. 
  719. File: geomview  Node: Common syntax, Prev: Conventions, Up: Conventions, Next: File names
  720.  
  721. Syntax Common to All OOGL File Formats
  722. --------------------------------------
  723.  
  724. Most OOGL object file formats are free-format ASCII --- any amount of
  725. white space (blanks, tabs, newlines) may appear between tokens (numbers,
  726. key words, etc.).  Line breaks are almost always insignificant, with a
  727. couple of exceptions as noted.  Comments begin with # and continue to
  728. the end of the line; they're allowed anywhere a newline is.
  729.  
  730. Binary formats are also defined for several objects; *Note Binary format::, and the individual object descriptions.
  731.  
  732. Typical OOGL objects begin with a key word designating object type,
  733. possibly with modifiers indicating presence of color information etc.
  734. In some formats the key word is optional, for compatibility with file
  735. formats defined elsewhere.  Object type is then determined by
  736. guessing from the file suffix (if any) or from the data itself.
  737.  
  738. Key words are case sensitive.  Some have optional prefix letters
  739. indicating presence of color or other data; in this case the order of
  740. prefixes is significant, e.g. `CNMESH' is meaningful but
  741. `NCMESH' is invalid.
  742.  
  743. 
  744. File: geomview  Node: File names, Prev: Common syntax, Up: Conventions, Next: Vertices
  745.  
  746. File Names
  747. ----------
  748.  
  749. When OOGL objects are read from disk files, the OOGL library uses the
  750. file suffix to guess at the file type.
  751.  
  752. If the suffix is unrecognized, or if no suffix is available (e.g. for an
  753. object being read from a pipe, or embedded in another OOGL object), all
  754. known types of objects are tried in turn until one accepts the data as
  755. valid.
  756.  
  757. 
  758. File: geomview  Node: Vertices, Prev: File names, Up: Conventions, Next: Surface normal directions
  759.  
  760. Vertices
  761. --------
  762.  
  763. Several objects share a common style of representing vertices with
  764. optional per-vertex surface-normal and color.  All vertices within an
  765. object have the same format, specified by the header key word.
  766.  
  767. All data for a vertex is grouped together (as opposed to e.g. giving
  768. coordinates for all vertices, then colors for all vertices, and so on).
  769.  
  770. The syntax is
  771.  
  772. `X  Y  Z'
  773.      (3-D floating-point vertex coordinates) or
  774. `X  Y  Z  W'
  775.      (4-D floating-point vertex coordinates)
  776.  
  777. optionally followed by
  778.  
  779. `NX  NY  NZ'
  780.      (normalized 3-D surface-normal if present)
  781.  
  782. optionally followed by
  783.  
  784. `R  G  B  A'
  785.      (4-component floating-point color if present, each component in range
  786.      0..1.  The A (alpha) component represents opacity: 0 transparent, 1
  787.      opaque.)
  788.  
  789.      optionally followed by
  790. `S T'
  791. `or'
  792. `S T U'
  793.  
  794. (two or three texture-coordinate values).
  795.  
  796. Values are separated by white space, and line breaks
  797. are immaterial.
  798.  
  799. Letters in the object's header key word must appear in a specific order;
  800. that's the reverse of the order in which the data is given for each vertex.
  801. So a `CN4OFF' object's vertices contain first the 4-component space
  802. position, then the 3-component normal, finally the 4-component color.
  803. You can't change the data order by changing the header key word; an
  804. `NCOFF' is just not recognized.
  805.  
  806. 
  807. File: geomview  Node: Surface normal directions, Prev: Vertices, Up: Conventions, Next: Transformation matrices
  808.  
  809. Surface normal directions
  810. -------------------------
  811.  
  812. Geomview uses normal vectors to determine how an object is shaded.
  813. The direction of the normal is significant in this calculation.
  814.  
  815. When normals are supplied with an object, the direction of the normal
  816. is determined by the data given.
  817.  
  818. When normals are not supplied with the object, Geomview computes normal
  819. vectors automatically; in this case normals point toward the side from
  820. which the vertices appear in counterclockwise order.
  821.  
  822. On parametric surfaces (Bezier patches), the normal at point P(u,v)
  823. is in the direction dP/du cross dP/dv.
  824.  
  825. 
  826. File: geomview  Node: Transformation matrices, Prev: Surface normal directions, Up: Conventions, Next: Binary format
  827.  
  828. Transformation matrices
  829. -----------------------
  830.  
  831. Some objects incorporate 4x4 real matrices for homogeneous object
  832. transformations.  These matrices act by multiplication on the right of
  833. vectors.  Thus, if p is a 4-element row vector representing homogeneous
  834. coordinates of a point in the OOGL object, and A is the 4x4 matrix, then
  835. the transformed point is p' = p A.  This matrix convention is common in
  836. computer graphics; it's the transpose of that often used in mathematics,
  837. where points are column vectors multiplied on the right of matrices.
  838.  
  839.  
  840. Thus for Euclidean transformations, the translation components appear in
  841. the fourth row (last four elements) of A.  A's last column (4th, 8th,
  842. 12th and 16th elements) are typically 0, 0, 0, and 1 respectively.
  843.  
  844. 
  845. File: geomview  Node: Binary format, Prev: Transformation matrices, Up: Conventions, Next: References
  846.  
  847. Binary format
  848. -------------
  849.  
  850. Many OOGL objects accept binary as well as ASCII file formats.
  851. These files begin with the usual ASCII token (e.g. `CQUAD')
  852. followed by the word `BINARY'.
  853. Binary data begins at the byte following the first newline after
  854. `BINARY'.  White space and a single comment may intervene, e.g.
  855.  
  856.      OFF BINARY    # binary-format "OFF" data follows 
  857.  
  858. Binary data comprise 32-bit integers and 32-bit IEEE-format floats, both
  859. in big-endian format (i.e., with most significant byte first).  This is
  860. the native format for 'int's and 'float's on Sun-3's, Sun-4's, and
  861. Irises, among others.
  862.  
  863. Binary data formats resemble the corresponding ASCII formats, with ints
  864. and floats in just the places you'd expect.  There are some exceptions
  865. though, specifically in the `QUAD', `OFF' and `COMMENT'
  866. file formats.  Details are given in the individual file format
  867. descriptions.  *Note QUAD::, *Note OFF::, and *Note COMMENT::.
  868.  
  869. Binary OOGL objects may be freely mixed in ASCII object streams:
  870.  
  871.      LIST
  872.      { = MESH BINARY
  873.      ... binary data for mesh here ...
  874.      }
  875.      { = QUAD
  876.          1 0 0   0 0 1   0 1 0  0 1 0
  877.      }
  878.  
  879. Note that ASCII data resumes immediately following the last byte of
  880. binary data.
  881.  
  882. Naturally, it's impossible to embed comments inside a binary-format OOGL
  883. object, though comments may appear in the header before the beginning of
  884. binary data.
  885.  
  886. 
  887. File: geomview  Node: References, Prev: Binary format, Up: Conventions, Next: Appearances
  888.  
  889. Embedded objects and external-object references
  890. -----------------------------------------------
  891.  
  892. Some object types (`LIST', `INST') allow references to other
  893. OOGL objects, which may appear literally in the data stream, be loaded
  894. from named disk files, or be communicated from elsewhere via named
  895. objects.  Gcl commands also accept geometry in these forms.
  896.  
  897. The general syntax is
  898.  
  899.       <oogl-object>  ::=
  900.          [ "{" ]
  901.              [ "define" `symbolname' ]
  902.              [ "appearance" `appearance' ]
  903.              [ ["="] `object-keyword' ...
  904.               | "<" `filename'
  905.               | ":" `symbolname' ]
  906.          [ "}" ]
  907.  
  908. where "quoted" items are literal strings (which appear without the
  909. quotes), [bracketed] items are optional, and | denotes alternatives.
  910. Curly braces, when present, must match; the outermost set of curly
  911. braces is generally required when the object is in a larger context,
  912. e.g. when it is part of a larger object or embedded in a Geomview
  913. command stream.
  914.  
  915. For example, each of the following three lines:
  916.          { define fred   QUAD 1 0 0  0 0 1  0 1 0  1 0 0 }
  917.  
  918.          { appearance { +edge } LIST { < "file1" } { : fred } }
  919.  
  920.          VECT 1 2 0   2 0   0 0 0   1 1 2
  921. is a valid OOGL object.  The last example is only valid when it is
  922. delimited unambiguously by residing in its own disk file.
  923.  
  924. The "<" construct causes a disk file to be read.  Note that this isn't a
  925. general textual "include" mechanism; a complete OOGL object must appear
  926. in the referenced file.
  927.  
  928. Files read using "<" are sought first in the directory of the file which
  929. referred to them, if any; failing that, the normal search path (set by
  930. Geomview's `load-path' command) is used.  The default search looks
  931. first in the current directory, then in the Geomview data directories.
  932.  
  933. The ":" construct allows references to symbols, created with
  934. `define'.  A symbol's initial value is a null object.  When a
  935. symbol is (re)defined, all references to it are automatically changed;
  936. this is a crucial part of the support for interprocess communication.
  937. Some future version of the documentation should explain this better...
  938.  
  939. Again, white space and line breaks are insignificant, and "#" comments
  940. may appear anywhere.
  941.  
  942.  
  943. 
  944. File: geomview  Node: Appearances, Prev: References, Up: Conventions, Next: Texture Mapping
  945.  
  946. Appearances
  947. -----------
  948.  
  949. Geometric objects can have associated "appearance" information,
  950. specifying shading, lighting, color, wireframe vs. shaded-surface
  951. display, and so on.  Appearances are inherited through object
  952. hierarchies, e.g. attaching an appearance to a `LIST' means that the
  953. appearance is applied to all the `LIST''s members.
  954.  
  955. Some appearance-related properties are relegated to "material" and
  956. "lighting" substructures.  Take care to note which properties belong to
  957. which structure.
  958.  
  959. Here's an example appearance structure including values for all
  960. attributes.  Order of attributes is unimportant.  As usual, white space
  961. is irrelevant.  Boolean attributes may be preceded by "+" or "-" to turn
  962. them on or off; "+" is assumed if only the attribute name appears.
  963. Other attributes expect values.
  964.  
  965. A "*" prefix on any attribute, e.g. "*+edge" or "*linewidth 2"
  966. or "material { *diffuse 1 1 .25 }", selects "override" status for
  967. that attribute.
  968.  
  969.      appearance {
  970.        +face               # (Do) draw faces of polygons.  On by default.
  971.        -edge               # (Don't) draw edges of polygons
  972.        +vect               # (Do) draw VECTs.  On by default.
  973.        -transparent        # (Disable) transparency. enabling transparency 
  974.                            # does NOT result in a correct Geomview picture, 
  975.                            # but alpha values are used in RenderMan snapshots.
  976.        -normal             # (Do) draw surface-normal vectors
  977.        normscale 1         # ... with length 1.0 in object coordinates
  978.  
  979.        +evert              # do evert polygon normals where needed so as
  980.                            #   to always face the camera
  981.  
  982.        -texturing          # (Disable) texture mapping
  983.        -backcull           # (Don't) discard clockwise-oriented faces
  984.        -concave            # (Don't) expect and handle concave polygons
  985.        -shadelines          # (Don't) shade lines as if they were lighted cylinders
  986.                    # These four are only effective where the graphics system
  987.                    # supports them, namely on GL and Open GL.
  988.  
  989.        -keepcolor          # Normally, when N-D positional coloring is enabled as
  990.                    # with geomview's (ND-color ...) command, all
  991.                    # objects' colors are affected.  But, objects with the
  992.                    # "+keepcolor" attribute are immune to N-D coloring.
  993.  
  994.        shading smooth      # or "shading constant" or "shading flat" or
  995.                            # or "shading csmooth".
  996.                            # smooth = Gouraud shading, flat = faceted,
  997.                            # csmooth = smoothly interpolated but unlighted.
  998.  
  999.        linewidth 1         # lines, points, and edges are 1 pixel wide.
  1000.  
  1001.        patchdice 10 10     # subdivide Bezier patches this finely in u and v
  1002.  
  1003.        material {         # Here's a material definition;
  1004.                            # it could also be read from a file as in
  1005.                            #  "material < file.mat"
  1006.  
  1007.            ka  1.0         # ambient reflection coefficient.
  1008.            ambient .3 .5 .3 # ambient color (red, green, blue components)
  1009.                            # The ambient contribution to the shading is
  1010.                            # the product of ka, the ambient color,
  1011.                            # and the color of the ambient light.
  1012.  
  1013.            kd  0.8         # diffuse-reflection coefficient.
  1014.            diffuse .9 1 .4 # diffuse color.
  1015.                              # (In "shading constant" mode, the surface
  1016.                              # is colored with the diffuse color.)
  1017.  
  1018.            ks 1.0          # specular reflection coefficient.
  1019.            specular 1 1 1  # specular (highlight) color.
  1020.            shininess  25   # specular exponent; larger values give
  1021.                            # sharper highlights.
  1022.  
  1023.            backdiffuse .7 .5 0 # back-face color for two-sided surfaces
  1024.                              # If defined, this field determines the diffuse
  1025.                              # color for the back side of a surface.
  1026.                              # It's implemented by the software shader, and
  1027.                              # by hardware shading on GL systems which support
  1028.                              # two-sided lighting, and under Open GL.
  1029.  
  1030.            alpha   1.0     # opacity; 0 = transparent (invisible), 1 = opaque.
  1031.                            # Ignored when transparency is disabled.
  1032.  
  1033.            edgecolor   1 1 0  # line & edge color
  1034.  
  1035.            normalcolor 0 0 0  # color for surface-normal vectors
  1036.        }
  1037.  
  1038.        lighting {         # Lighting model
  1039.  
  1040.            ambient  .3 .3 .3  # ambient light
  1041.  
  1042.            replacelights   # "Use only the following lights to
  1043.                            # illuminate the objects under this
  1044.                            # appearance."
  1045.                            # Without "replacelights", any lights listed
  1046.                            # are added to those already in the scene.
  1047.  
  1048.                            # Now a collection of sample lights:
  1049.            light { 
  1050.                color  1 .7 .6      # light color
  1051.                position  1 0 .5 0  # light position [distant light]
  1052.                                    # given in homogeneous coordinates.
  1053.                                    # With fourth component = 0,
  1054.                                    # this means a light coming from
  1055.                                    # direction (1,0,.5).
  1056.            }
  1057.  
  1058.            light {                        # Another light.
  1059.                color 1 1 1
  1060.                position  0 0 .5 1  # light at finite position ...
  1061.                location camera     # specified in camera coordinates.
  1062.                                    # (Since the camera looks toward -Z,
  1063.                                    # this example places the light
  1064.                                    # .5 unit behind the eye.)
  1065.                # Possible "location" keywords:
  1066.                #  global    light position is in world (well, universe) coordinates
  1067.                #             This is the default if no location specified.
  1068.                #  camera   position is in the camera's coordinate system
  1069.                #  local    position is in the coordinate system where
  1070.                #                   the appearance was defined
  1071.            }
  1072.        }                   # end lighting model
  1073.        texture {
  1074.              clamp st               # or "s" or "t" or "none"
  1075.              file lump.tiff         # file supplying texture-map image
  1076.              alphafile mask.pgm.Z   # file supplying transparency-mask image
  1077.              apply blend            # or "modulate" or "decal"
  1078.              transform  1 0 0 0     # surface (s,t,0,1) * tfm -> texture coords
  1079.                         0 1 0 0
  1080.                         0 0 1 0
  1081.                        .5 0 0 1
  1082.  
  1083.              background 1 0 0 1     # relevant for "apply blend"
  1084.        }
  1085.      }                     # end appearance
  1086.  
  1087.  
  1088. There are rules for inheritance of appearance attributes when several
  1089. are imposed at different levels in the hierarchy.
  1090.  
  1091. For example, Geomview installs a backstop appearance which provides
  1092. default values for most parameters; its control panels install other
  1093. appearances which supply new values for a few attributes; user-supplied
  1094. geometry may also contain appearances.
  1095.  
  1096. The general rule is that the child's appearance (the one closest to the
  1097. geometric primitives) wins.
  1098. Further, appearance controls with "override" status
  1099. (e.g. *+face or material { *diffuse 1 1 0 })
  1100. win over those without it.
  1101.  
  1102. Geomview's appearance controls use the "override" feature so as to be
  1103. effective even if user-supplied objects contain their own appearance settings.
  1104. However, if a user-supplied object contains an appearance field with
  1105. override status set, that property will be immune to Geomview's controls.
  1106.  
  1107. 
  1108. File: geomview  Node: Texture Mapping, Prev: Appearances, Up: Conventions, Next: Object File Formats
  1109.  
  1110. Texture Mapping
  1111. ---------------
  1112.  
  1113. Some platforms support texture-mapped objects.
  1114. (On those which don't, attempts to use texture mapping are silently
  1115. ignored.)  A texture is specified as part of an appearance structure,
  1116. as in *Note Appearances::.  Briefly, one provides a texture image,
  1117. which is considered to lie in a square in `(s,t)' parameter space in
  1118. the range 0 <= s <= 1, 0 <= t <= 1.  Then one provides a geometric primitive,
  1119. with each vertex tagged with `(s,t)' texture coordinates.  If texturing
  1120. is enabled, the appropriate portion of the texture image is pasted onto
  1121. each face of the textured object.
  1122.  
  1123. There is (currently) no provision for inheritance of part of a texture
  1124. structure; if the `texture' keyword is mentioned in an appearance,
  1125. it supplants any other texture specification.
  1126.  
  1127. The appearance attribute `texturing' controls whether textures are
  1128. used; there's no performance penalty for having texture { ... } fields
  1129. defined when texturing is off.
  1130.  
  1131. The available fields are:
  1132.  
  1133.      clamp    none  -or-  s  -or-  t  -or-  st
  1134.        Determines the meaning of texture coordinates outside the range 0..1.
  1135.        With `clamp none', the default, coordinates are interpreted
  1136.        modulo 1, so (s,t) = (1.25,0), (.25,0), and (-.75,0) all refer to
  1137.        the same point in texture space.  With `s' or `t' or
  1138.        `st', either or both of s- or t-coordinates less than 0 or
  1139.        greater than 1 are clamped to 1 or 0, respectively.
  1140.  
  1141.      file    filename
  1142.      alphafile    filename
  1143.        Specifies image file(s) containing the texture.
  1144.        The `file' file's image specifies color or lightness information;
  1145.        the `alphafile' if present, specifies a transparency ("alpha") mask;
  1146.        where the mask is zero, pixels are simply not drawn.
  1147.        Several image file formats are available; the file type must be
  1148.        indicated by the last few characters of the file name:
  1149.          .ppm or .ppm.Z or .ppm.gz  24-bit 3-color image in PPM format
  1150.          .pgm or .pgm.Z or .pgm.gz  8-bit grayscale image in PGM format
  1151.          .sgi or .sgi.Z or .sgi.gz  8-bit, 24-bit, or 32-bit SGI image
  1152.          .tiff                8-bit or 24-bit TIFF image
  1153.          .gif               GIF image
  1154.        (Though 4-channel TIFF images are possible, and could
  1155.        represent both color and transparency information in one image,
  1156.        that's not supported in geomview at present.)
  1157.        For this feature to work, some programs must be available in
  1158.        geomview's search path:
  1159.          zcat  for .Z files
  1160.          gzip  for .gz files
  1161.          tifftopnm for .tiff files
  1162.          giftoppm for .gif files
  1163.  
  1164.        If an `alphafile' image is supplied, it must be the same size
  1165.        as the `file' image.
  1166.  
  1167.  
  1168.      apply    modulate  -or-  blend  -or-  decal
  1169.        Indicates how the texture image is applied to the surface.
  1170.        Here the "surface color" means the color that surface would have
  1171.        in the absence of texture mapping.
  1172.  
  1173.        With `modulate', the default, the texture color (or lightness,
  1174.        if textured by a gray-scale image) is multiplied by the surface color.
  1175.  
  1176.        With `blend', texture blends between the `background' color
  1177.        and the surface color.  The `file' parameter must specify a
  1178.        gray-scale image.  Where the texture image is 0, the surface color is
  1179.        unaffected; where it's 1, the surface is painted in the color given
  1180.        by `background'; and color is interpolated for intermediate values.
  1181.  
  1182.        With `decal', the `file' parameter must specify a
  1183.        3-color image.  If an `alphafile' parameter is present,
  1184.        its value interpolates between the surface color (where alpha=0)
  1185.        and the texture color (where alpha=1).  Lighting does not affect the
  1186.        texture color in `decal' mode; effectively the texture is
  1187.        constant-shaded.
  1188.  
  1189.      background  R G B A
  1190.        Specifies a 4-component color, with R, G, B, and A floating-point
  1191.        numbers normally in the range 0..1, used when `apply blend'
  1192.        is selected.
  1193.  
  1194.      transform `transformation-matrix'
  1195.        Expects a list of 16 numbers, or one of the other ways of representing
  1196.        a transformation (`: handlename' or `< filename').
  1197.        The 4x4 transformation matrix is applied to texture coordinates,
  1198.        in the sense of a 4-component row vector (s,t,0,1) multiplied on
  1199.        the left of the matrix, to produce new coordinates (s',t')
  1200.        which actually index the texture.
  1201.  
  1202. 
  1203. File: geomview  Node: Object File Formats, Prev: Texture Mapping, Up: OOGL File Formats, Next: QUAD
  1204.  
  1205. Object File Formats
  1206. ===================
  1207.  
  1208. * Menu:
  1209.  
  1210. * QUAD::        List of quadrilaterals.
  1211. * MESH::        Rectangularly-connected mesh.
  1212. * BBP and BEZ::        List of Bezier surface patches.
  1213. * OFF::            Polyhedra: polygons with shared vertices.
  1214. * VECT::        List of points and lines.
  1215. * SKEL::        List of points and lines, with shared vertices.
  1216. * SPHERE::        Sphere
  1217. * INST::        Transformed Instance of another object.
  1218. * LIST::        List of other objects.
  1219. * TLIST::        Collection of 4x4 transformation matrices.
  1220. * GROUP::        Obsolete format for collections of objects.
  1221. * DISCGRP::             Discrete Group objects.
  1222. * COMMENT::        Comment object, for caching information.
  1223.  
  1224.  
  1225. 
  1226. File: geomview  Node: QUAD, Prev: Object File Formats, Up: Object File Formats, Next: MESH
  1227.  
  1228. QUAD: collection of quadrilaterals
  1229. ----------------------------------
  1230.  
  1231. The conventional suffix for a `QUAD' file is `.quad'.
  1232.  
  1233. The file syntax is
  1234.  
  1235.         [C][N][4]QUAD  -or-  [C][N][4]POLY           # Key word
  1236.         VERTEX  VERTEX  VERTEX  VERTEX  # 4*N vertices for some N
  1237.         VERTEX  VERTEX  VERTEX  VERTEX
  1238.         ...
  1239.  
  1240. The leading key word is `[C][N][4]QUAD' or `[C][N][4]POLY',
  1241. where the optional `C' and `N' prefixes indicate that each vertex
  1242. includes colors and normals respectively.  That is, these files
  1243. begin with one of the words
  1244.  
  1245. `QUAD' `CQUAD' `NQUAD' `CNQUAD' `POLY'
  1246. `CPOLY' `NPOLY' `CNPOLY'
  1247.  
  1248. (but not `NCQUAD' or `NCPOLY').  `QUAD' and `POLY'
  1249. are synonymous; both forms are allowed just for compatibility with
  1250. ChapReyes.
  1251.  
  1252. Following the key word is an arbitrary number of groups of four
  1253. vertices, each group describing a quadrilateral.  See the Vertex syntax
  1254. above.  The object ends at end-of-file, or with a closebrace if
  1255. incorporated into an object reference (see above).
  1256.  
  1257. A `QUAD BINARY' file format is accepted; *Note Binary format::.  The
  1258. first word of binary data must be a 32-bit integer giving the number of
  1259. quads in the object; following that is a series of 32-bit floats,
  1260. arranged just as in the ASCII format.
  1261.  
  1262. 
  1263. File: geomview  Node: MESH, Prev: QUAD, Up: Object File Formats, Next: BBP and BEZ
  1264.  
  1265. MESH: rectangularly-connected mesh
  1266. ----------------------------------
  1267.  
  1268. The conventional suffix for a `MESH' file is `.mesh'.
  1269.  
  1270. The file syntax is
  1271.  
  1272.      [U][C][N][Z][4][u][v][n]MESH # Key word
  1273.      [NDIM]                 # Space dimension, present only if nMESH
  1274.      NU NV            # Mesh grid dimensions
  1275.                                   # NU*NV vertices, in format specified
  1276.                                   # by initial key word
  1277.      VERTEX(u=0,v=0)  VERTEX(1,0)  ... VERTEX(NU-1,0)
  1278.      VERTEX(0,1) ...    VERTEX(NU-1,1)
  1279.      ...
  1280.      VERTEX(0,NV-1) ... VERTEX(NU-1,NV-1)
  1281.  
  1282. The key word is  `[U][C][N][Z][4][u][v][n]MESH'.
  1283. The optional prefix characters mean:
  1284.  
  1285. `U'
  1286.      Each vertex includes a 3-component texture space parameter.
  1287.      The first two components are the usual `S' and `T' texture
  1288.      parameters for that vertex; the third should be specified as zero.
  1289. `C'
  1290.      Each vertex (see Vertices above) includes a 4-component color.
  1291. `N'
  1292.      Each vertex includes a surface normal vector.
  1293. `Z'
  1294.      Of the 3 vertex position values, only the Z component is present; X and
  1295.      Y are omitted, and assumed to equal the mesh (u,v) coordinate so X
  1296.      ranges from 0 .. (Nu-1), Y from 0 .. (Nv-1) where Nu and Nv are the mesh
  1297.      dimensions -- see below.
  1298. `4'
  1299.      Vertices are 4D, each consists of 4 floating values.  `Z' and
  1300.      `4' cannot both be present.
  1301. `u'
  1302.      The mesh is wrapped in the u-direction, so the 
  1303.      (0,v)'th vertex is connected to the (NU-1,v)'th for all v.
  1304. `v'
  1305.      The mesh is wrapped in the v-direction, so the (u,0)'th vertex is
  1306.      connected to the (u,NV-1)'th for all u.  Thus a u-wrapped or
  1307.      v-wrapped mesh is topologically a cylinder, while a uv-wrapped mesh is a
  1308.      torus.
  1309. `n'
  1310.      Specifies a mesh whose vertices live in a higher dimensional space.
  1311.      The dimension follows the "MESH" keyword.  Each vertex then has NDIM
  1312.      components.
  1313.  
  1314. Note that the order of prefix characters is significant; a colored,
  1315. u-wrapped mesh is a `CuMESH' not a `uCMESH'.
  1316.  
  1317. Following the mesh header are integers NU and NV,
  1318. the dimensions of the mesh.
  1319.  
  1320. Then follow NU*NV vertices, each in the form given by the header.
  1321. They appear in v-major order, i.e. if we name each vertex by (u,v)
  1322. then the vertices appear in the order
  1323.  
  1324.      (0,0) (1,0) (2,0) (3,0) ...  (NU-1,0)
  1325.      (0,1) (1,1) (2,1) (3,1) ...  (NU-1,1)
  1326.      ...
  1327.      (0,Nv-1)        ...  (NU-1,NV-1)
  1328.  
  1329. A `MESH BINARY' format is accepted; *Note Binary format::.  The
  1330. values of NU and NV are 32-bit integers; all other values
  1331. are 32-bit floats.
  1332.  
  1333. 
  1334. File: geomview  Node: BBP and BEZ, Prev: MESH, Up: Object File Formats, Next: OFF
  1335.  
  1336. Bezier Surfaces
  1337. ---------------
  1338.  
  1339. The conventional file suffixes for Bezier surface files are `.bbp'
  1340. or `.bez'.  A file with either suffix may contain either type of
  1341. patch.
  1342.  
  1343. Syntax:
  1344.  
  1345.        [ST]BBP -or- [C]BEZ<NU><NV><ND>[_ST]
  1346.                  # NU, NV are u- and v-direction 
  1347.                  # polynomial degrees in range 1..6
  1348.                  # ND = dimension: 3->3-D, 4->4-D (rational)
  1349.                  # (The '<' and '>' do not appear in the input.)
  1350.                  # NU,NV,ND are each a single decimal digit.
  1351.                  # BBP form implies NU=NV=ND=3 so BBP = BEZ333.
  1352.  
  1353.              # Any number of patches follow the header
  1354.                  # (NU+1)*(NV+1) patch control points
  1355.                  # each 3 or 4 floats according to header
  1356.        VERTEX(u=0,v=0)  VERTEX(1,0) ... VERTEX(NU,0)
  1357.        VERTEX(0,1)               ... VERTEX(NU,1)
  1358.        ...
  1359.        VERTEX(0,NV)           ... VERTEX(NU,NV)
  1360.  
  1361.                  # ST texture coordinates if mentioned in header
  1362.        `S'(u=0,v=0)    `T'(0,0)    `S'(0,NV) `T'(0,NV)
  1363.        `S'(NU,0)    `T'(NU,0)    `S'(NU,NV) `T'(NU,NV)
  1364.  
  1365.                  # 4-component float (0..1) R G B A colors
  1366.                  # for each patch corner if mentioned in header
  1367.        `RGBA'(0,0)   `RGBA'(0,NV)
  1368.        `RGBA'(NU,0)  `RGBA'(NU,NV)
  1369.  
  1370. These formats represent collections of Bezier surface patches, of
  1371. degrees up to 6, and with 3-D or 4-D (rational) vertices.
  1372.  
  1373. The header keyword has the forms `[ST]BBP' or
  1374. `[C]BEZ<NU><NV><ND>[_ST]' (the '<' and '>' are
  1375. not part of the keyword.
  1376.  
  1377. The `ST' prefix on `BBP', or `_ST' suffix on
  1378. `BEZuvn', indicates that each patch includes four pairs of
  1379. floating-point texture-space coordinates, one for each corner of the
  1380. patch.
  1381.  
  1382. The `C' prefix on `BEZuvn' indicates a colored patch,
  1383. including four sets of four-component floating-point colors (red, green,
  1384. blue, and alpha) in the range 0..1, one color for each corner.
  1385.  
  1386. NU and NV, each a single digit in the range 1..6, are the
  1387. patch's polynomial degree in the u and v direction respectively. 
  1388.  
  1389. ND is the number of components in each patch vertex, and must be
  1390. either `3' for 3-D or `4' for homogeneous coordinates, that
  1391. is, rational patches.
  1392.  
  1393. `BBP' patches are bicubic patches with 3-D vertices, so `BBP'
  1394. = `BEZ333' and `STBBP' = `BEZ333_ST'.
  1395.  
  1396. Any number of patches follow the header.  Each patch comprises a series
  1397. of patch vertices, followed by optional (s,t) texture coordinates,
  1398. followed by optional (r,g,b,a) colors.
  1399.  
  1400. Each patch has (NU+1)*(NV+1) vertices in v-major order, so that if we
  1401. designate a vertex by its control point indices (u,v) the order is
  1402.           (0,0) (1,0) (2,0) ...  (NU,0)
  1403.           (0,1) (1,1) (2,1) ...  (NU,1)
  1404.           ...
  1405.           (0,NV)            ...  (NU,NV)
  1406. with each vertex containing either 3 or 4 floating-point numbers
  1407. as specified by the header.
  1408.    
  1409. If the header calls for ST coordinates, four pairs of floating-point
  1410. numbers follow: the texture-space coordinates for the (0,0),
  1411. (NU,0), (0,NV), and (NU,NV) corners of the
  1412. patch, respectively.
  1413.  
  1414. If the header calls for colors, four four-component (red, green, blue,
  1415. alpha) floating-point colors follow, one for each patch corner.
  1416.  
  1417. The series of patches ends at end-of-file, or with a closebrace if
  1418. incorporated in an object reference.
  1419.  
  1420. 
  1421.